home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan / Opus 5 - Magellan.iso / Extras / opussdk / docs / misc.doc < prev    next >
Text File  |  1996-09-07  |  10KB  |  376 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/Atoh
  4. dopus5.library/BtoCStr
  5. dopus5.library/BuildKeyString
  6. dopus5.library/BytesToString
  7. dopus5.library/ConvertRawKey
  8. dopus5.library/DivideToString
  9. dopus5.library/DivideU
  10. dopus5.library/Itoa
  11. dopus5.library/ItoaU
  12. dopus5.library/QualValid
  13. dopus5.library/Random
  14. dopus5.library/StrCombine
  15. dopus5.library/StrConcat
  16. dopus5.library/Seed
  17. dopus5.library/Atoh                                       dopus5.library/Atoh
  18.  
  19.     NAME
  20.         Atoh - convert a hex ascii string to a long
  21.  
  22.     SYNOPSIS
  23.         Atoh(string, len)
  24.                A0     D0
  25.  
  26.         long Atoh(char *, long);
  27.  
  28.     FUNCTION
  29.         Converts an ascii representation of a hex value to a long value.
  30.  
  31.     INPUTS
  32.         string - string to convert
  33.         len - length of string to convert, or -1 for the whole string
  34.  
  35.     RESULT
  36.         Returns the long value equivalent to the ascii string.
  37.  
  38. dopus5.library/BtoCStr                                 dopus5.library/BtoCStr
  39.  
  40.     NAME
  41.         BtoCStr - convert a BCPL string to a C string
  42.  
  43.     SYNOPSIS
  44.         BtoCStr(bstr, cstr, length)
  45.                  A0    A1     D0
  46.  
  47.         void BtoCStr(BSTR, char *, long);
  48.  
  49.     FUNCTION
  50.         Converts the supplied BSTR to a null-terminated C string.
  51.  
  52.     INPUTS
  53.         bstr - BCPL pointer to BSTR to convert
  54.         cstr - buffer to store converted string in
  55.         length - size of buffer
  56.  
  57.     RESULT
  58.         The string is converted. BSTRs are limited to 255 characters.
  59.  
  60. dopus5.library/BuildKeyString                   dopus5.library/BuildKeyString
  61.  
  62.     NAME
  63.         BuildKeyString - build a commodities key code string
  64.  
  65.     SYNOPSIS
  66.         BuildKeyString(code, qual, qual_mask, qual_same, buffer)
  67.                         D0    D1      D2         D3        A0
  68.  
  69.         void BuildKeyString(USHORT, USHORT, USHORT, USHORT, char *);
  70.  
  71.     FUNCTION
  72.         Takes the supplied key code and qualifier and converts them to an
  73.         ASCII string that is compatible with Commodities.
  74.  
  75.     INPUTS
  76.         code - key code
  77.         qual - key qualifier
  78.         qual_mask - mask of the qualifiers to care about
  79.         qual_same - which qualifiers are equivalent
  80.  
  81.     RESULT
  82.         The string is stored in the supplied buffer. String lenghts can
  83.         vary but for safety this buffer should be at least 80 bytes.
  84.  
  85.     SEE ALSO
  86.         commodities.library/ParseIX()
  87.  
  88. dopus5.library/BytesToString                     dopus5.library/BytesToString
  89.  
  90.     NAME
  91.         BytesToString - build a string representation of a byte size
  92.  
  93.     SYNOPSIS
  94.         BytesToString(bytes, buffer, places, separator)
  95.                        D0      A0      D1       D2
  96.  
  97.         void BytesToString(ULONG, char *, short, char);
  98.  
  99.     FUNCTION
  100.         This routine takes a long value and creates a string to represent
  101.         that value as an expression of size. Some examples are :
  102.  
  103.                  102       ->    102b
  104.                  5804      ->    5K
  105.                  1829382   ->    1.8M
  106.  
  107.     INPUTS
  108.         bytes - byte value
  109.         buffer - buffer to store result
  110.         places - number of decimal places. This must be set to 1 currently.
  111.         separator - column separator (eg a comma could produce "1,193")
  112.  
  113.     RESULT
  114.         The string is stored in the buffer. The buffer should be at least
  115.         16 bytes long.
  116.  
  117. dopus5.library/ConvertRawKey                     dopus5.library/ConvertRawKey
  118.  
  119.     NAME
  120.         ConvertRawKey - convert a key from the raw key code
  121.  
  122.     SYNOPSIS
  123.         ConvertRawKey(code, qual, keybuf)
  124.                        D0    D1     A0
  125.  
  126.         BOOL ConvertRawKey(USHORT, USHORT, char *);
  127.  
  128.     FUNCTION
  129.         Takes the supplied code and qualifier and returns the equivalent
  130.         key in the current key map. This function provides a convenient path
  131.         to the console.device's RawKeyConvert() routine.
  132.  
  133.     INPUTS
  134.         code - key code
  135.         qual - key qualifier
  136.         keybuf - buffer to store key
  137.  
  138.     RESULT
  139.         The key is stored in the supplied buffer. Most keys only require
  140.         a single byte but in case one is larger the buffer should be at
  141.         least 8 bytes in size.
  142.  
  143.     SEE ALSO
  144.         console.device/RawKeyConvert()
  145.  
  146. dopus5.library/DivideToString                   dopus5.library/DivideToString
  147.  
  148.     NAME
  149.         DivideToString - divide two numbers, store the result as ASCII
  150.  
  151.     SYNOPSIS
  152.         DivideToString(buffer, numerator, denominator, places, separator)
  153.                          A0       D0          D1         D2        D3
  154.  
  155.         void DivideToString(char *, ULONG, ULONG, short, char);
  156.  
  157.     FUNCTION
  158.         This routine divides the numerator by the denominator, and stores
  159.         the result with one decimal place precision as an ASCII string.
  160.  
  161.     INPUTS
  162.         string - buffer to store result
  163.         numerator - number to divide
  164.         denominator - number to divide by
  165.         places - decimal places, must be set to 1 for now
  166.         separator - columns separator (eg a comma might produce "1,103")
  167.  
  168.     RESULT
  169.         The division is performed and the result stored in the buffer.
  170.  
  171. dopus5.library/DivideU                                 dopus5.library/DivideU
  172.  
  173.     NAME
  174.         DivideU - 32bit unsigned division with remainder
  175.  
  176.     SYNOPSIS
  177.         DivideU(numerator, denominator, remainptr, utillib)
  178.                    D0           D1          A0        A1
  179.  
  180.         ULONG DivideU(ULONG, ULONG, ULONG *, struct Library *);
  181.  
  182.     FUNCTION
  183.         This routine calls the utility.library UDivMod32() routine, and
  184.         returns the result. Any remainder is stored in the supplied
  185.         variable.
  186.  
  187.     INPUTS
  188.         numerator - number to divide
  189.         denominator - number to divide by
  190.         remainptr - pointer to ULONG to store the remainder
  191.         utillib - pointer to UtilityBase
  192.  
  193.     RESULT
  194.         Returns the integer result. The remainder is stored in the supplied
  195.         variable.
  196.  
  197.     SEE ALSO
  198.         utility.library/UDivMod32()
  199.  
  200. dopus5.library/Itoa                                       dopus5.library/Itoa
  201.  
  202.     NAME
  203.         Itoa - converts signed integer to a string
  204.  
  205.     SYNOPSIS
  206.         Itoa(num, string, separator)
  207.               D0     A0       D1
  208.  
  209.         void Itoa(long, char *, char);
  210.  
  211.     FUNCTION
  212.         This routine takes the supplied signed number and converts it to
  213.         an ASCII string.
  214.  
  215.     INPUTS
  216.         num - number to convert
  217.         string - string to store result
  218.         separator - column separator character, or 0 for no separator.
  219.  
  220.     RESULT
  221.         The string is stored in the supplied buffer.
  222.  
  223.     SEE ALSO
  224.         ItoaU()
  225.  
  226. dopus5.library/ItoaU                                     dopus5.library/ItoaU
  227.  
  228.     NAME
  229.         ItoaU - converts unsigned integer to a string
  230.  
  231.     SYNOPSIS
  232.         ItoaU(num, string, separator)
  233.                D0     A0       D1
  234.  
  235.         void ItoaU(long, char *, char);
  236.  
  237.     FUNCTION
  238.         This routine takes the supplied unsigned number and converts it to
  239.         an ASCII string.
  240.  
  241.     INPUTS
  242.         num - number to convert
  243.         string - string to store result
  244.         separator - column separator character, or 0 for no separator.
  245.  
  246.     RESULT
  247.         The string is stored in the supplied buffer.
  248.  
  249.     SEE ALSO
  250.         Itoa()
  251.  
  252. dopus5.library/QualValid                             dopus5.library/QualValid
  253.  
  254.     NAME
  255.         QualValid - mask out invalid qualifiers
  256.  
  257.     SYNOPSIS
  258.         QualValid(qual)
  259.                    D0
  260.  
  261.         USHORT QualValid(USHORT);
  262.  
  263.     FUNCTION
  264.         Masks out invalid qualifiers from the supplied value and returns
  265.         the result.
  266.  
  267.     INPUTS
  268.         qual - qualifier mask
  269.  
  270.     RESULT
  271.         The return value is the new qualifier mask. Only the following
  272.         qualifiers are considered "valid" for operations within Opus :
  273.  
  274.             IEQUALIFIER_LCOMMAND, IEQUALIFIER_RCOMMAND,
  275.             IEQUALIFIER_LSHIFT, IEQUALIFIER_RSHIFT,
  276.             IEQUALIFIER_LALT, IEQUALIFIER_RALT,
  277.             IEQUALIFIER_CONTROL, IEQUALIFIER_NUMERICPAD
  278.  
  279. dopus5.library/Random                                    dopus5.library/Random
  280.  
  281.     NAME
  282.         Random - generate a psuedo-random number
  283.  
  284.     SYNOPSIS
  285.         Random(limit)
  286.                 D0
  287.  
  288.         long Random(long);
  289.  
  290.     FUNCTION
  291.         Returns a psuedo-random number between 0 and 'limit' inclusive.
  292.  
  293.     INPUTS
  294.         limit - upper limit of number
  295.  
  296.     RESULT
  297.         Returns random number.
  298.  
  299.     SEE ALSO
  300.         Seed()
  301.  
  302. dopus5.library/StrCombine                           dopus5.library/StrCombine
  303.  
  304.     NAME
  305.         StrCombine - combine two strings into one buffer
  306.  
  307.     SYNOPSIS
  308.         StrCombine(buffer, first, second, size)
  309.                      A0      A1     A2     D0
  310.  
  311.         BOOL StrCombine(char *, char *, char *, long);
  312.  
  313.     FUNCTION
  314.         Combines the two supplied strings into the one buffer.
  315.  
  316.     INPUTS
  317.         buffer - buffer to store result
  318.         first - first string
  319.         second - second string
  320.         size - size of buffer
  321.  
  322.     RESULT
  323.         Returns TRUE if both strings fitted in the buffer, or FALSE
  324.         if they had to be truncated.
  325.  
  326.     SEE ALSO
  327.         StrConcat()
  328.  
  329. dopus5.library/StrConcat                             dopus5.library/StrConcat
  330.  
  331.     NAME
  332.         StrConcat - concatenate two strings
  333.  
  334.     SYNOPSIS
  335.         StrConcat(first, second, size)
  336.                     A0     A1     D0
  337.  
  338.         BOOL StrConcat(char *, char *, long);
  339.  
  340.     FUNCTION
  341.         Joins the second string to the end of the first string.
  342.  
  343.     INPUTS
  344.         first - first string
  345.         second - string to join
  346.         size - size of first buffer
  347.  
  348.     RESULT
  349.         The second string is joined to the end of the first string.
  350.         This function returns TRUE if the second string fitted in the
  351.         buffer, or FALSE if it had to be truncated.
  352.  
  353.     SEE ALSO
  354.         StrCombine()
  355.  
  356. dopus5.library/Seed                                       dopus5.library/Seed
  357.  
  358.     NAME
  359.         Seed - seed the random number generator
  360.  
  361.     SYNOPSIS
  362.         Seed(seed)
  363.               D0
  364.  
  365.         void Seed(long);
  366.  
  367.     FUNCTION
  368.         Seeds the random number generator.
  369.  
  370.     INPUTS
  371.         seed - value to seed generator with
  372.  
  373.     SEE ALSO
  374.         Random()
  375.  
  376.